home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
ASTRONOM
/
H139.ZIP
/
RO101.ZIP
/
RO.DOC
< prev
next >
Wrap
Text File
|
1991-11-04
|
36KB
|
1,255 lines
.. \"-------------------------------------------------------
.. \"
.. \" ro.doc
.. \"
.. \" documentation for the ro text formatter
.. \"
.. \" NOTE: This documentation is in "ro"
.. \" format and will not read correctly unless
.. \" it is processed by ro and postprocessed by
.. \" an ro filter. To read the document on
.. \" a computer with the "more" pager, the
.. \" command line:
.. \"
.. \" ro ro.doc | termnull | more
.. \"
.. \" should work.
.. \"
.. \"-------------------------------------------------------
.so tmac.m
.PH "'ro v1.00''\*(DT'"
.PF "''Page #''"
.nr Pi 5
.nr Ps 1
.ls 1
.ll 65
.sp 2
.ce
\fBRO.DOC\fR
.sp 1
.ce
\fBDocumentation for the RO Text Formatter\fR
.sp 2
.ce
\fICopyright Information\fR:
.nf
ro, version 1.00:
Portions copyright (c) 1989 by Ted A. Campbell
Bywater Software
P. O. Box 4023
Duke Station
Durham, NC 27706
Contains portions of ROFF4, Version 1.61
(c) 1985 by Konrad Kwok
20 3rd Street, Section M
Fariview Park,
Hong Kong
Contains portions of ROFF4, Version 1.60
(c) 1983, 4 by Ernest E. Bergmann
Physics, Building #16
Lehigh University
Bethlehem, Pa. 18015
.fi
.P
\"ro" and its predecessor ROFF4 are based on
the ROFF text processor described in Brian W. Kernigan
and P. J. Plauger's now-classic text \fISoftware Tools\fR
(Reading, MA: Addison-Wesley, 1976).
.P
Permission is hereby granted for all commercial and
non-commercial reproduction and distribution of this
material provided this notice is included.
.ne 4
.sp 2
.ce
\fIGeneral Description\fR
.P
\"ro" is a text formatter. It is based on the
CP/M ROFF4 formatter,
which was an expanded version of ROFF, itself based on the
formatter in Kernigan and Plauger's \fISoftware Tools\fR.
It is written in the C programming language, and has
been successfully compiled on both Unix and DOS
computers.
.P
\"ro" is designed to be downwardly-compatible
with the Unix-based "nroff" text formatter,
and efforts have been made to make this
version of ro as much like nroff as possible,
although many nroff features (like
withholding traps) are not yet implemented
in ro.
\"ro" adds some features to nroff, such as
debug and verbose modes (using the "-x" and "-v"
flags, respectively), and a number of predefined
commands which are usually implemented as macros
in nroff (e.g., .HE, which sets a three-part
page header).
.P
Included with this implementation of ro
is a package of macros named "tmac.m".
This implements some of the macros
found in the popular nroff-based
\"-mm" macro package.
.ne 8
.sp 2
.ce
\fIUsing ro\fR
.sp 1
\fIInvoking the Program\fR:
.P
\"ro" is command-line based,
and by default takes its input
from "standard input."
All output is sent to "standard output."
The command
.sp
.ti 5
\ro
.sp
by itself would simply read input from
the keyboard and output to the screen.
Utilizing the command-line "<" and ">"
operators in Unix and DOS, you can redirect
both the standard input and the standard output.
Thus the command
.sp
.ti 5
\ro <infile >outfile
.sp
would take its input from "infile" and send output
to "outfile."
.P
It is possible to send output
directly to the printer utilizing
output redirection. In Unix, the command
.sp
.ti 5
\ro <infile >/dev/lp
.sp
would take its input from "infile" and
send the output to "/dev/lp",
which is usually implemented as the line printer.
Similarly, in DOS, the command
.sp
.ti 5
\ro <infile >prn
.sp
would send output to the "PRN" device,
which is normally attached to the printer.
\fBHowever\fR, it is usually undesirable
to send output directly to a printer
(or the screen, for that matter),
since ro output will likely
include unprocessed printer escape codes.
For this reason, it is deirable to use an
output "post-processor" (see below
under \fIUsing a Post-Processor\fR).
.P
\"ro" can also take its input from files named
directly on the command line (without the
\"<" operator). The command
.sp
.ti 5
\ro infile
.sp
would read input directly from "filename",
and the command
.sp
.ti 5
\ro file1 file2 file3
.sp
would read input from files "file1",
\"file2", and "file3" successively.
Note that input must be from named files
(and not from standard input)
if you wish to utilize the "-s" flag
option (described below).
.ne 4
.sp 2
\fICommand-Line Flags\fR
.P
\"ro" utilizes a number of command-line flags
to control the program.
All flags are processed before text input is received.
.P
The \fB-s\fR flag, causes the formatter to stop (pause)
at the start of each page of output; a tone at the
console is sounded and the program
waits until the RETURN key is pressed. It
is essential for printers that are fed single sheets
at a time!
\fBPlease note\fR that to utilize this feature,
you must name files directly on the command
line. (This is because the key-press to resume
printing must itself come from standard input.)
.P
The \fB-o[page or range]\fR flag
is used to selectively generate output of ONLY certain
pages. It is useful to retype pages that got "eaten"
by the printer (Henry Harpending's aptly put language).
To retype only page 23, say, make the option: -o23
To retype pages 23 through 29 use: -o23-29
To retype pages 23 to the end use: -23-
These options changes the values of the internal
variables, FIRSTPAGE and LASTPAGE which originally
have the values of 1 and 30000, respectively.
.P
The comamnd-line flag \fB-f\fR will introduce a formfeed (0CH)
into the output stream at the bottom of every page.
This is usefull, e.g., if you want to output in compressed
pitch where the end of the printed page might not
corrrespond to the end of the physical page.
.P
The flag \fB-v\fR turns on "verbose" mode.
In this mode, some chit-chatty messages are
printed to "standard error" (almost always
the console), including some rather important
error messages. Normally, only fatal error
messages are printed when verbose mode is not on
(because ro is expected
to do much of its work in the background).
.P
The option \fB-x\fR turns on the "debug" flag so as to
print out lots of diagnostics to the STDERR [console].
Probably only useful for those who are trying to
trace the operation of the formatter for elusive
\"bugs".
Specifying the "-x" flag will also turn on
the "verbose" mode (but not \fIvice versa\fR).
.ne 4
.sp 2
\fIDefault Values\fR
.P
Using ro, you can make nice printouts of a file,
with as little or as much help from the program as you want,
depending on the commands. There are default values for all
parameters, so if you don't put any commands in at all, your
file will come out with filled, right-justified lines. The
default line-length is 65 characters; the default page-
length is 66 lines per page. "Filled lines" means that as
many input words as possible are packed onto a line before
it is printed; "non-filled" lines go through the formatter
w/o rearrangement. "Adjusted" or "right-justified" simply means that
spaces are added between words to make all the right margins
line up nicely. To change a parameter, use the appropriate
commands below. All commands have the form of a period
followed by two letters. A command line should have nothing
on it but the command and its arguments (if any); any text
would be lost.
.ne 4
.sp 2
\fIUsing a Postprocessor\fR
.P
\"ro" does not handle printer-specific control codes itself;
instead, it sends out simple (but consistent) escape
sequences which have to be "post-processed" by another program
to fit a particular terminal or printer.
Three example post-processors are provided
with ro:
.sp
.nf
termnull strips out all printer codes
termansi prepares sequences for an ANSI-
compatible terminal
termnx10 prepares sequences for the Star
NX10 printer
.fi
.sp
All of these postprocessors take their input
from standard input, and send their output
to standard output.
.P
You can use the "|" ("pipe") operator
to send the output from ro directly to
a postprocessor, and you can use "|" again
to send the post-processor's output to
a print spooler, pager, or other program.
Here are some useful examples: The command
.sp
.ti +5
\ro filename | termnull | more
.sp
involes ro with input from "filename",
pipes its output to termnull, where all
printer sequences are stripped away,
and then sends its output to the "more"
pager. Utilizing this sequence, one
could preview "filename" on any terminal,
although no printer-specific sequences would
be shown. For ANSI-compatible terminals
(including DOS computers which have ANSI.SYS
installed), the sequence
.sp
.ti +5
\ro filename | termansi | more
.sp
would do the same as the previous command,
except that boldface would appear
in bold, and italics would appear underlined
in the output.
The Unix sequence
.sp
.ti +5
\ro filename | termnx10 | lp
.sp
would take input from "filename",
set up sequences for the Star NX10
printer, and send the output
to the "lp" print spooler.
Similarly, under DOS,
.sp
.ti +5
\ro filename | termnull >prn
.sp
would take input from "filename",
strip out all printer codes, and
send the output to the PRN device
(normally attached to the printer).
.P
The escape codes sent out by ro are simple, and are
listed at the end of this document.
With these and the source code to termnx10 (included),
it should
be relatively easy to write a post-processor
for almost any terminal or device.
.ne 8
.sp 2
.ce
\fIInput to ro\fR
.sp 1
\fIInput Text\fR
.P
\"ro" generally reads input until it can fill out
a complete line of text (specfied by the "line length"
variable, set by the command .ll).
By default, it then "adjusts" or justifies these
input line when putting them out.
Both the "filling" and the "adjustment" of lines
can be toggled on and off (see the commands
described below, .fi, .nf, .ad, .na).
.P
Extra space will separate text sentences. The sentence
is recognized by a trailing ':',';','!','?', or a '.'. For
the '.' there is the additional requirement that either two
or more spaces must spaces must follow it, or that it is at the
end of the source line.
.ne 4
.sp 2
\fIInput Commands and Their Arguments\fR
.P
\"ro" is controlled internally by commands
that are identified by a period ('.') in the
first place on a line.
Be carefull: if you inadvertently place
a period in the first place in a line,
\"ro" will try to interpret it
as a command.
\"ro" commands are either one or two letters
in length, and are all case-sensitive,
i.e., the command
.sp
.ti +5
.In
.sp
is different from the command
.sp
.ti +5
.in
.sp
and so on.
By convention, built-in commands are lower-case,
and macros (see below) are upper-case;
however, this is not a rule, and we have elected
to place all non-nroff compatible commands
in upper case, since this is how they appear
in nroff implementations.
.P
A command argument can be either ABSOLUTE or RELATIVE :
.br
.nf
.sp
.in 5 sets the indent value to 5 spaces
.in +5 sets the indent value to the CURRENT value+5
.ls -1 sets the line spacing to the current value-1
.fi
.P
Also, all commands have a minimum and maximum value
that will weed out any odd command settings (like setting
the line spacing to zero, for example. It won't let you do
that, but it could be changed (by recompiling
the program).
.P
Some commands cause a "break", which is noted in the
table below. Before such a command goes into effect, the
current line of text is put out, whether it is completely
filled or not. (this is what happens at the end of a
paragraph, for example.) A line beginning with spaces or a
tab will cause a break, and will be indented by that many
spaces (or tabs) regardless of the indent value at that time
(this is a "temporary indent", which can also be set
explicitly). An all blank line also causes a break. If you
find that some lines that are indented strangely, and it's
not obvious WHY, look at which commands are causing a break,
and which aren't. For instance:
.sp
.nf
.fi
.ti 0
this is a line of text
.in 8
<- blank line
more text for the machine to play with
.fi
.P
At first glance it seems obvious that the line "this is a
line of text" will be indented zero spaces, but it won't -
it will be indented 8. The indent command does NOT cause a
break (although the .ti does) so it will not cause the line
to be put out before setting the indent value to 8. Then,
when the blank line is encountered, it will cause a break -
and "this is a line of text" will be indented incorrectly.
The above example will give the following lines.
.sp
.fi
.ti +5
this is a line of text
.sp
.ti +5
more text for the machine to play with
.br
.in
.P
It is worthwhile considering placing a ".br", the
break command, before each use of ".in".
.P
Certain system variables are "stacked" to enable
reversion to earlier environments instead of "hardcoded"
defaults. For example:
.sp
.nf
.ls 1
.
.
.ls
.sp
.fi
The first command will produce single line spacing (which is
the default, but which may have been set otherwise at the
beginning of the manuscript). The second command causes
resumption of the original line spacing (either the default
or whatever had been chosen previously). Stacked variables
include: linespacing, indent column, line length,
translation flag character, page length, top and bottom
margin sizes, unexpandable space character, output width,
and tabsize.
.nf
.ne 8
.sp 4
*********************** Table of Commands *********************
Command Break? Default stacked Function
------- ------ ------- ------- ---------
A. nroff-compatible commands (* denotes compatibility limitation)
--------------------------------------------------------------
.. string no string is "mere" comment
(or end of macro definition)
.ad no initially on turn right justification
on (use .na to turn off);
only applicable if
"filling" is also on.
.bp n yes n = +1 begin page numbered n
.br yes cause a break (this
line is not justified)
.ce n yes n = 1 center next n lines
.di name (*) no junk.$$$ diversion file
(see "PREPROCESSOR")
.de name no define (multiline)
macro ("PREPROCESSOR")
.ds name string no null string define string replace-
ment ("PREPROCESSOR")
.em end macro
(see "PREPROCESSOR")
.ex no immediate abort back to
system
.fi yes start filling lines
.ig string no "ignore" string (see ..)
.in n no n = 10 Yes set indent value to n
.ll n no n = 65 Yes set line length (right
margin)
.ls n no n = 1 Yes set line spacing to n
.na no initially on turn right justification
off (use .ad to turn on)
.ne n no/yes n = 2 "need" n lines; if have
them no action; else
begins new page
.nf yes stop filling lines
.nr name n no n=0 No create or modify
register variable
(see "PREPROCESSOR")
.pl n no n = 66 Yes sets page length to n
.pm print macros defined
(for debugging)
.po no 0 No sets page offset (spaces
at left margin of every
line.
.so filename no ignored Yes reads named file into
input stream; cannot be
invoked from keyboard
input.
.sp n yes n = 1 space down n lines
.ta n no n = 8 Yes sets value of tab space
.tc c no ~ Yes set translation flag
character, see .tr
.ti n yes n = 0 set temp. indent of n
.tm string send message to terminal
(console); like a comment
but displayed to
operator during run.
.ne 8
B. non-nroff-compatible commands (must be upper-case)
--------------------------------------------------
.BJ yes break with right
justification (current
line only)
.DB n no n = 0(NO) set debug flag 1 for
diagnostics
.EF /../../../ no blanks even footer titling
.EH /../../../ no blanks even header titling
.FF n no n = 1(yes) initially, formfeeds
are "off". Can turn
them on. Each page
then terminated with
one formfeed.
.FO /../../../ no empty sets both even and odd
page footers
.HE /../../../ no empty sets both even and odd
page headers
.M1 no n = 2 Yes set topmost margin to n
.M2 no n = 2 Yes set 2nd top margin to n
lines
.M3 no n = 2 Yes 1st bottom margin to n
lines
.M4 no n = 2 Yes bottom-most margin to n
lines
.OF /../../../ no empty odd page footer title
.OH /../../../ no empty odd page header title
.SC c no blank Yes space character; the
visible character
that will be trans-
literated to unexpanded
blank.
.SR show registers defined
.SS show strings defined
.ST n no n = 1 (yes) stop (pause) at each page
start; initially off;
may also be enabled by
the -s option.
.ne 27
.sp 2
Here's what the page parameters look like:
|<--------output width ------------------------>|
|- po --| ( "po = page offset")
_ _________________________________________________
| | top margin(m1) - (includes header) |
| |-----------------------------------------------|
| | top margin 2 |
| |-----------------------------------------------|
P | : : |
A | :<-indent : |
G | : : |
E | :lots and lots of silly text and: |
L | :other garbage. Get the picture?: |
E | :This is a temp. indentation: |
N | : : |
G | : right margin -> : |
T | : : |
H | : : |
| |-----------------------------------------------|
| | margin 3 |
| |-----------------------------------------------|
| | margin 4 - (includes footer,perhaps ff) |
- -------------------------------------------------
.fi
Minimum acceptable values for M1, M2, M3, and M4: if M1 is set
to zero, no header will be shown (even if one was declared).
Similarly, if M4 is set to zero, no footer will be displayed.
.P
To change the default for any parameter, you must alter ro.h
and recompile.
.ne 4
.sp 2
\fISome Notes on Input Commands\fR
.P
\fB".ce"\fR.
If you want to center lots of lines, but don't
want to count them, do something like this:
.sp
.nf
.ce 1000
lots and
lots of words to
be centered
.ce 0
.sp
will give the lines:
.ce 1000
lots and
lots of words to
be centered
.ce 0
.fi
.sp
.P
\fB".ti"\fR.
A new paragraph may be caused by using the temporary indent
command, like
.sp
.nf
.ti +5
.fi
.sp
or by simply beginning the paragraph with a tab.
.ne 4
.sp 2
\fIHeader and Footer Commands\fR
.P
A page number can be incorporated into any header or
footer by putting a "#" in the title where you want the number
to go:
.nf
.he //This is a witty header title for page #//
.fi
Each time this is printed at the top of a page, the current
page number will be substituted for the "#".
Each footer and header are ".in 0", even if text is
indented.
.P
Headers and footers are in three parts. These parts are left
justified, centered, and right justifed. Any of these three
parts may be left out. One may pick the
headers and footers separately for even and odd pages. For
example, one could place even and odd page numbers at the
bottom outside of each page by:
.sp
.nf
.EF /Page #///
.OF ///Page #/
.fi
.P
Any printable character, here the '/', can be used to
delimit the three strings that make up the titles, so long
as it is not the backslash character ('\\') and is
not present in any of the three strings.
.P
The program can be made to wait for the operator to
load single sheets of paper by the -s option and/or by the
command: .ST
.P
If you want to send the output to a file, and don't want the
page breaks in there set margins 1-4 to zero.
.ne 4
.sp 2
\fIPrinter Control Input\fR
.P
At present, ro recognizes only five sequences
for printer control. These, with their input
symbols, are:
.sp
.nf
\\fR Switch to Roman Font
\\fI Switch to \fIItalic\fR Font
\\fB Switch to \fBBold\fR Font
\\u Up \uone-half\d line
\\d Down \done-half\u line
.fi
.sp
The "Roman" (or perhaps "Regular") font turns off
both Italic and Bold fonts. The \\u and \\d
commands are useful in depicting superscripts
and subscripts.
.P
Fonts can also be switched using the ".ft"
input command. For example, the command
.sp
.ti +5
.ft R
.sp
would set the Roman font for subsequent input.
.ne 8
.sp 2
.ce
\fIThe Preprocessor\fR
.sp 1
\fIString Definitions\fR
.P
In the following we describe the advanced macro
preprocessing features of this formatter which provide users
with labor saving tools but which are probably not necessary
at first. The beginning user may be able to achieve most
goals without the "preprocessing", but by using an editor
more then otherwise. The more advanced user will begin to
appreciate these features more.
.P
For example, in:
.sp
Today, \\*(da, is special.
.sp
the block, "\\*(da", would be replaced as this sentence is
being input. If a prior string definition of the form:
.ds da "January 1, 1983"
.ds da "January 1, 1983"
had been processed previously then the example, after text
substitution, would become:
.sp
.ti +5
Today, \*(da, is special.
.P
The string definition command, .ds, expects two arguments:
a name of one or two characters (case is significant),
and then either a single word (no whitespace) or
a string delimited by double quotation marks ("...").
A single-letter string name is expanded on output
when the letter is preceded by "\\*".
For example, one could define a string N using
.sp
.ti +5
.ds N "Alfred E. Newman"
.sp
and then whenever the sequence \\*N appears
in the input text, the string "\*N" would
be output.
A two-letter string name is expanded on output
when it is preceded by "\\*(".
Thus, in the example above, the string "da"
is defined, and output with "\\*(da",
yielding "\*(da". Did it work?
.ne 4
.sp 2
\fINumber Registers\fR
.P
Similar to string definitions are number register
variables, which are created and modified with the \fB.nr\fR
command. Variables are useful for enumeration such as
equation numbering:
.sp
.ti +5
.nr eq 1
.nr eq 1
.sp
would create a register named "eq" with the current value
of 1. The the text might use it with, say:
.sp
.ti +5
x = y+1 \\n(eq
.sp
which would be converted on input into:
.sp
.ti +5
x = y+1 \n(eq
.sp
A subsequent instruction:
.sp
.ti +5
.nr eq +1
.nr eq +1
.sp
would take the current value of "eq" and increase it by 1
(so that it would now be 2 in our example:
.sp
.ti +5
a = b+c \\n(eq
.sp
would become:
.sp
.ti +5
a = b+c \n(eq
.P
Number Register values are expanded on output
in a manner similar to string variables, except
that "n" (must be lower-case) is used in place
of "*". Thus the register variable "P" would
be expanded by "\\nP", and the register "Pi"
would be expanded by "\\n(Pi", just as "eq"
is expanded by "\\n(eq" above.
.P
There is a special, reserved insertion, \#\, which
will provide the current page number. It should prove
useful in setting up tables of contents (see "diversions",
below).
.P
Since we have defined a special register name, '#',
we should comment on what happens if you create a register
instruction with that name, such as:
.sp
.ti +5
.nr # +1
.sp
You will be changing the value of the page number of the
FOLLOWING pages. This is useful for leaving gaps in the
pagination for later inclusion of full page illustrations.
This feature is demonstrated (tested) in the file, MARGINS.
I wish to thank Henry Harpending for suggesting this.
.P
\"ro" includes some predefined number registers
that are available to users. These are:
.sp
.nf
dy current day of the month
mo current month as integer (1-12)
yr current year -1900
.fi
.sp
Thus, a user could say,
\"Today's date is \\n(dy/\\n(mo/\\n(yr",
and this would be ouput as
\"Today's date is \n(dy/\n(mo/\n(yr".
.ne 4
.sp 2
\fIUsing Backslashes\fR
.P
The backslash character has other properties.
It can be placed into the input by repeating
it, namely, "\\\\" becomes "\\". (useful for delaying
substitutions). For example, defining:
.sp
.ti +5
.ds EN "\\n(eq"
.ds EN "\\n(eq"
.sp
will identify "EN" with "\\n(eq" and so our equation
example above could have been:
.sp
.ti +5
a = b + c \*(EN
.sp
Delaying the evaluation of "eq" until EN is invoked
(instead of when it was defined) means that the proper
numbering of equations will occur instead of wrongly
supplying the value of "eq" from the time that EN was
first created.
Utilizing this technique,
the "tmac.m" package defines a macro for the
current date, which is:
.sp
.ti +5
.ds DT "19\\\\n(yr/\\\\n(mo/\\\\n(dy"
.ds DT "19\\n(yr/\\n(mo/\\n(dy"
.sp
This would be expanded using "\\*(DT",
which would produce "\*(DT" (did it work?).
.ne 4
.sp 2
\fIMacro Definitions\fR
.P
"Macro" definitions are used when we wish to
identify several lines with an insertion. Such definitions
are created with the .de ["define macro"] and completed with
the .. ["end macro"] commands. For example, we might wish
to use the following sequence over and over again at the
start of paragraphs:
.sp
.nf
.sp 1
.ne 2
.ti +5
.fi
.P
to separate the paragraphs by blank lines, keep them from
starting excessively close to the bottom of the page, and
indenting them 5 spaces to the right of the current left
margin.
.nf
.sp
.de P
.sp 1
.ne 2
.ti +5
..
.fi
.P
Subsequently, whenever we wished to start a paragraph we
would create a command line:
.sp
.ti +5
.P
.sp
instead of more tediously creating every time the three
commands we mentioned above.
.P
The names of all macros, strings, and number
registers are "case sensitive". That is to say that
capitalization and/or lower case are distinguished and, say,
.sp
.ti +5
.p
.sp
Would not be recognized as the same as the sample macro we
just defined.
The macro is read until a line beginning with ".em" (end macro)
or simply ".." is reached.
.P
A macro command may contain parameters(s). For example
.sp
.nf
.de He
$0
..
.de He
$0
..
.fi
.sp
defines a simple macro for printing a heading.
When the line ".He Heading"
appears at the beginning of a line, the word "Heading"
will be printed, i.e.:
.sp
.He Heading
.P
The maximum number of parameters for a macro is 10 ($0-$9).
The parameter(s) must be on the same line of the macro call.
The parameters are separate by a non-alphanumeric character
except '+' and '-' which
appear as the first character of the parameter line. If the
first character is a alphanumeric character, then white space
will be assumed as the delimiter. An example can be found
above. If the require parameter(s) is/are not defined by the
macro call, then the parameter(s) will be treated as null
string.
.ne 4
.sp 2
\fIDiversions\fR
.P
There is another object formed and used somewhat
like a macro; it is called a "diversion (file)" and is
useful for making lists such as references [notes] and
tables of contents. A diversion is created or continued
with the command: \fB.di\fR [diversion].
It is ended with the same command
(the command to begin the diversion should
have a one- or two-letter name argument;
the command to end it should have no argument.
A diversion can grow to be quite large and is, in "ro", a
disk file. To "regurgitate" the diversion file, its
name must be entered as a command at the beginning of a line.
.P
For example, the "tmac.m" macros define .FS
(start footnote -- actually and endnote)
as including the command ".di no".
Internally, at this point, ro creates a disk file
named "no_ro.div" and begins placing all input
in this file.
The macro ".FE" (footnote end) includes the command ".di".
At this point the diversion to "no_ro.div" is
ceased, and input is again read as normal.
For each .FS - .FE pair, this sequence is
repeated, so that the diversion file collects
all the footnotes.
Finally, the macro ".PN" (printout notes)
includes the command ".no" which ro
recognizes as the signal to send out all
the material collected in the diversion file.
\".PN" is placed last in the text file, so that
the notes follow after the text.
.ne 8
.sp 2
.ce
\fIUsing the tmac.m Macro Package\fR
.P
The file "tmac.m" included with this distribution
defines some macros for use in processing documents.
These are roughly equivalent to the nroff "-mm" macros
of similar names.
You can very easily customize this package and add
to it for your own uses.
.P
\fIParagraph Control\fR.
Using the tmac.m macros, the command
.sp
.ti +5
.P
.sp
is used to begin a paragraph.
There are two number registers associated with
this command:
.sp
.ti +5
.nf
Ps paragraph spacing, and
.ti +5
Pi paragraph indent.
.fi
.sp
Each time .P is called, "Ps" lines are skipped, and a
temporary indent of "Pi" characters is set.
.P
\fIThe Date String\fR.
With the tmac.m package, the current date
is stored in the string "DT" and can
therefore be output at any point with \\*(DT.
This yields "\*(DT", and is used in the page
header for this documentation (see at the top of this page).
.P
\fIEndnote Control\fR.
Although ro does not currently support footnotes
(because it does not implement a withholding trap),
there are three macros and a string definition to
support endnotes. These are:
.sp
.nf
\\*F prints current note number, superscript
.FS starts text of note
.FE ends text of note
.PN prints out all notes collected
.fi
.sp
The command ".FS" begins diversion to a separate file,
so you must be careful to end the text of the note with
the ".FE" command. Also, be sure to include the ".PN"
command at the point where you want the notes to be
printed out (normally at the very end of the file).
.P
\fIFont Control\fR.
The tmac.m package contains three macros
consistent with the "-mm" package for switching
fonts. These are:
.sp
.nf
.R switch to Roman (regular) font
.I switch to Italic font
.B switch to Bold font
.fi
.P
\fIPage Header and Footer Control\fR.
The tmac.m package defines two macros
consistent with "-mm" which reset page
headers and footers:
.sp
.nf
.PH page header
.PF page footer
.fi
.sp
Note that the arguments to these must be three-part titles
enclosed in double quotation marks, e.g.,
.sp
.fi
.PH "'left'center'right'"
.sp
This differs from the usage of the built-in .HE
and .FO commands.
.P
\fIText and Block Macros\fR.
Finally, the tmac.m package defines macros
not found in "-mm" that I have found helpful
in writing papers. These are:
.sp
.nf
.TA begin double-spaced text segment
.TZ end double-spaced text segment
.BA begin single-spaced indented block
.BZ end single-spaced indented block
.fi
.ne 8
.sp 2
.ce
\fIro Output and Post-Processor Development\fR
.P
The five sequences to control the printer are
sen, on output, as the ESCAPE character (0x1b hex,
27 decimal) followed by a single ASCII character.
These sequences are:
.sp
.nf
ESCAPE 'R' Set Roman Font
ESCAPE 'I' Set Italic Font
ESCAPE 'B' Set Bold Font
ESCAPE 'u' Up One-Half Line
ESCAPE 'd' Down One-Half Line
.fi
.sp
An ro postprocessor should intercept any
ESCAPE character, then determine based
on the next character following it what
codes to send out.
.P
As an example, the folowing is the entire
text of the "termnx10" postprocessor.
It should be relatively easy to alter
the escape code sequences here to suit any
printer.
\fBPlease note\fR that in the version below
we have had to doule each backslash character
so that it would print correctly when output
by ro. If you want to cut this program
out of ro.doc to compile it, you'll need
to convert each double backslash to a single one.
.sp
.nf
#include "stdio.h"
#include "term.h"
char progname[] = "termnx10";
main()
{
register int c;
while( !feof( stdin ))
{
c = getchar();
switch( c )
{
case ESCAPE:
getpc();
break;
case EOF:
break;
default:
putchar( c );
break;
}
}
}
getpc()
{
register int c;
c = getchar();
switch( c )
{
case ROMAN:
roman();
break;
case ITALIC:
italic();
break;
case BOLD:
bold();
break;
case HALFUP:
halfup();
break;
case HALFDOWN:
halfdown();
break;
default:
fprintf( stderr, "%s: unrecognized output escape sequence ESC-0x%x \n", progname, c );
break;
}
}
roman()
{
printf( "\\0335\\033H" );
}
italic()
{
printf( "\\0334" );
}
bold()
{
printf( "\\033G" );
}
halfup()
{
printf( "\\033j\\022" );
}
halfdown()
{
printf( "\033J\022" );
}
--------------------------------------------
Here's the included "term.h" file:
--------------------------------------------
#define ESCAPE 0x1b
/** Single-character printer code designations ***/
#define ROMAN 'R' /* Restore "roman" or "regular" font */
/* Should turn off Bold and Italic */
#define ITALIC 'I' /* Switch to italics or underline */
#define BOLD 'B' /* Switch to bold */
#define HALFUP 'u' /* Half-line up */
#define HALFDOWN 'd' /* Half-line down */
.fi
